package com.smart.community.region.service;

import java.util.List;
import java.util.Map;

/**
 * 房户聚合统计服务接口
 *
 * @author Wu.Liang
 * @since 2024-12-21
 */
public interface IHouseholdAggregationService {

    // ==================== Controller调用的方法 ====================

    /**
     * 获取住户基础统计信息
     * @param communityIds 社区ID列表
     * @return 基础统计信息
     */
    Map<String, Object> getBasicStats(List<Long> communityIds) throws Exception;

    /**
     * 获取住户详细统计信息
     * @param communityIds 社区ID列表
     * @return 详细统计信息
     */
    Map<String, Object> getDetailedStats(List<Long> communityIds) throws Exception;

    /**
     * 获取住户分布统计
     * @param communityIds 社区ID列表
     * @return 分布统计信息
     */
    Map<String, Object> getDistributionStats(List<Long> communityIds) throws Exception;

    /**
     * 获取住户趋势分析
     * @param communityIds 社区ID列表
     * @param days 天数
     * @return 趋势分析数据
     */
    Map<String, Object> getTrendAnalysis(List<Long> communityIds, Integer days) throws Exception;

    // ==================== 原有接口方法 ====================

    /**
     * 按区域统计房户数量
     * @param regionIds 区域ID列表
     * @return 区域ID与房户数量的映射
     */
    Map<Long, Integer> countHouseholdsByRegion(List<Long> regionIds) throws Exception;

    /**
     * 按社区统计房户数量
     * @param communityIds 社区ID列表
     * @return 社区ID与房户数量的映射
     */
    Map<Long, Integer> countHouseholdsByCommunity(List<Long> communityIds) throws Exception;

    /**
     * 按楼栋统计房户数量
     * @param buildingIds 楼栋ID列表
     * @return 楼栋ID与房户数量的映射
     */
    Map<Long, Integer> countHouseholdsByBuilding(List<Long> buildingIds) throws Exception;

    /**
     * 按单元统计房户数量
     * @param unitIds 单元ID列表
     * @return 单元ID与房户数量的映射
     */
    Map<Long, Integer> countHouseholdsByUnit(List<Long> unitIds) throws Exception;

    /**
     * 获取房户入住率趋势数据
     * @param regionId 区域ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 趋势数据列表
     */
    List<Object> getHouseholdOccupancyTrend(Long regionId, String startDate, String endDate) throws Exception;

    /**
     * 获取房户分布统计数据
     * @param regionId 区域ID
     * @return 分布统计数据
     */
    Object getHouseholdDistribution(Long regionId) throws Exception;

    /**
     * 导出房户统计报表
     * @param regionId 区域ID
     * @param type 报表类型
     * @return 导出文件下载地址
     */
    String exportHouseholdStats(Long regionId, String type) throws Exception;
}
